<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Dynamic shared libraries</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Installation and Build Guide" />
    <link rel="up" href="build_unix.html" title="Chapter 7.  Building Berkeley DB for UNIX/POSIX" />
    <link rel="prev" href="build_unix_install.html" title="Installing Berkeley DB" />
    <link rel="next" href="build_unix_test.html" title="Running the test suite under UNIX" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Dynamic shared libraries</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="build_unix_install.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 7.  Building Berkeley DB for UNIX/POSIX
    </th>
          <td width="20%" align="right"> <a accesskey="n" href="build_unix_test.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="build_unix_shlib"></a>Dynamic shared libraries</h2>
          </div>
        </div>
      </div>
      <p>
        <span class="bold"><strong>Warning</strong></span>: the following
        information is intended to be generic and is likely to be
        correct for most UNIX systems. Unfortunately, dynamic shared
        libraries are not standard between UNIX systems, so there may
        be information here that is not correct for your system. If
        you have problems, consult your compiler and linker manual
        pages, or your system administrator.
    </p>
      <p> 
        The Berkeley DB dynamic shared libraries are created with
        the name libdb-<span class="bold"><strong>major</strong></span>.<span class="bold"><strong>minor</strong></span>.
        so, where <span class="bold"><strong>major</strong></span> is the major version number and
        <span class="bold"><strong>minor</strong></span> is the minor
        version number. Other shared libraries are created if Java and
        Tcl support are enabled: specifically, libdb_java-<span class="bold"><strong>major</strong></span>.<span class="bold"><strong>minor</strong></span>.so
        and libdb_tcl-<span class="bold"><strong>major</strong></span>.<span class="bold"><strong>minor</strong></span>.so. 
    </p>
      <p>
        On most UNIX systems, when any shared library is created,
        the linker stamps it with a "SONAME". In the case of Berkeley
        DB, the SONAME is libdb-<span class="bold"><strong>major</strong></span>.<span class="bold"><strong>minor</strong></span>.so. 
        It is important to realize that applications linked against a shared
        library remember the SONAMEs of the libraries they use and not the
        underlying names in the filesystem. 
    </p>
      <p>
        When the Berkeley DB shared library is installed, links are
        created in the install lib directory so that libdb-<span class="bold"><strong>major</strong></span>.<span class="bold"><strong>minor</strong></span>.so, 
        libdb-<span class="bold"><strong>major</strong></span>.so, and libdb.so all refer to the same
        library. This library will have an SONAME of libdb-<span class="bold"><strong>major</strong></span>.<span class="bold"><strong>minor</strong></span>.so. 
    </p>
      <p>
        Any previous versions of the Berkeley DB libraries that are
        present in the install directory (such as libdb-2.7.so or
        libdb-2.so) are left unchanged. (Removing or moving old shared
        libraries is one drastic way to identify applications that
        have been linked against those vintage releases.)
    </p>
      <p>
        Once you have installed the Berkeley DB libraries, unless
        they are installed in a directory where the linker normally
        looks for shared libraries, you will need to specify the
        installation directory as part of compiling and linking
        against Berkeley DB. Consult your system manuals or system
        administrator for ways to specify a shared library directory
        when compiling and linking applications with the Berkeley DB
        libraries. Many systems support environment variables (for
        example, LD_LIBRARY_PATH or LD_RUN_PATH), or system
        configuration files (for example, /etc/ld.so.conf) for this
        purpose.
    </p>
      <p>
        <span class="bold"><strong>Warning</strong></span>: some UNIX
        installations may have an already existing
        <code class="filename">/usr/lib/libdb.so</code>, and this library
        may be an incompatible version of Berkeley DB. 
    </p>
      <p> 
        We recommend that applications link against libdb.so (for
        example, using -ldb). Even though the linker uses the file
        named libdb.so, the executable file for the application
        remembers the library's SONAME 
        (libdb-<span class="bold"><strong>major</strong></span>.<span class="bold"><strong>minor</strong></span>.so).
        This has the effect of marking the applications with the versions they
        need at link time. Because applications locate their needed SONAMEs when they are
        executed, all previously linked applications will continue to
        run using the library they were linked with, even when a new
        version of Berkeley DB is installed and the file
        <code class="filename">libdb.so</code> is replaced with a new
        version. 
    </p>
      <p> 
        Applications that know they are using features specific to
        a particular Berkeley DB release can be linked to that
        release. For example, an application wanting to link to
        Berkeley DB major release "3" can link using -ldb-3, and
        applications that know about a particular minor release number
        can specify both major and minor release numbers; for example,
        -ldb-3.5. 
    </p>
      <p> 
        If you want to link with Berkeley DB before performing
        library installation, the "make" command will have created a
        shared library object in the <code class="filename">.libs</code>
        subdirectory of the build directory, such as
        <code class="filename">build_unix/.libs/libdb-major.minor.so</code>.
        If you want to link a file against this library, with, for
        example, a major number of "3" and a minor number of "5", you
        should be able to do something like the following:
    </p>
      <pre class="programlisting">cc -L BUILD_DIRECTORY/.libs -o testprog testprog.o -ldb-3.5
env LD_LIBRARY_PATH="BUILD_DIRECTORY/.libs:$LD_LIBRARY_PATH" ./testprog</pre>
      <p> 
        where <span class="bold"><strong>BUILD_DIRECTORY</strong></span> is
        the full directory path to the directory where you built
        Berkeley DB. 
    </p>
      <p>
        The libtool program (which is configured in the build
        directory) can be used to set the shared library path and run
        a program. For example, the following runs the gdb debugger on
        the db_dump utility after setting the appropriate paths:
    </p>
      <pre class="programlisting">libtool gdb db_dump</pre>
      <p> 
        Libtool may not know what to do with arbitrary commands (it
        is hardwired to recognize "gdb" and some other commands). If
        it complains the mode argument will usually resolve the
        problem:
    </p>
      <pre class="programlisting">libtool --mode=execute my_debugger db_dump</pre>
      <p>
        On most systems, using libtool in this way is exactly
        equivalent to setting the LD_LIBRARY_PATH environment variable
        and then executing the program. On other systems, using
        libtool has the virtue of knowing about any other details on
        systems that don't behave in this typical way. 
    </p>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="build_unix_install.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="build_unix.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="build_unix_test.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Installing Berkeley
        DB </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Running the test suite under
        UNIX</td>
        </tr>
      </table>
    </div>
  </body>
</html>
